home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / OVERLAY / OVRUMB12 / OVRUMB.DOC < prev    next >
Text File  |  1994-09-20  |  8KB  |  221 lines
  1.                 OvrUMB version 1.2
  2.               by Jean-Marc Lasgouttes
  3.                ─────────────────────────────
  4.  
  5.  
  6.  
  7. Overview
  8. ─────────
  9.  
  10. The purpose of this unit for Turbo Pascal 6/7 is to allow your programs
  11. that use overlays to free more conventional memory.  This is made possible
  12. by the relocation of the overlay buffer in upper memory on systems that
  13. support that kind of memory.
  14.  
  15. This unit should be compatible with the use of OvrInitEMS, OvrInitXMS (from
  16. the unit OverXMS - overxms.zip at garbo.uwasa.fi) or the procedures from the
  17. Streams unit (streams15.zip by Duncan Murdoch).  The purpose of all these
  18. procedures is to speed up the overlay reading by keeping the overlay file in
  19. EMS or XMS memory.  It is recommended to use OvrInitEMS/XMS or the streams
  20. unit in conjunction with OvrUMB.
  21.  
  22. This unit is released to the Public Domain.  Feel free to use it in your
  23. applications and distribute it, as long as this documentation is included.
  24. You can distribute a modified version of it, as long as credit is given to me
  25. as the original author; in this case, I would appreciate to get a copy of
  26. your modifications.  Although this unit has been tested on several systems,
  27. there is no warranty that it will work for your application and I should
  28. not be liable of any damage that it may cause.  However, I would be glad
  29. to try to correct any problem that you may encounter (see my address at the
  30. end of this document).
  31.  
  32.  
  33.  
  34. Why you should use OvrUMB
  35. ──────────────────────────
  36.  
  37. If you use overlays in your applications, you are probably aware that
  38. all the free memory that you can get will be welcome.  One way to gain
  39. memory is to use the upper memory which is accessible for real-mode
  40. programs on a wide range of systems (most 80386/486/... and some
  41. 8086/286).  With this unit, your applications will make use of upper
  42. memory if it is available, with a slight modification of your code.
  43.  
  44. The idea of this unit is very simple: Borland Pascal overlay manager
  45. uses a part of the heap as a buffer where it loads the overlaid code
  46. that needs to be executed. OvrMovBufToUMB tries to allocate a buffer
  47. of at least the same size in upper memory and to set the variables of
  48. the overlay manager to point to this new buffer. The old block can
  49. then be disposed of and is added to the heap. The gains in memory will
  50. be equal to the size of the biggest overlaid unit (20-30k in my case)
  51. if you use the default buffer.  But I find it more efficient to
  52. overlay as many units as possible and to declare a buffer of 60-80k
  53. with OvrSetBuf. This will free more memory and the slowdown will be
  54. hardly noticeable. In this case, OvrUMB will free even more
  55. conventional memory (as long as there is a 60-80k contiguous upper
  56. memory block on the host computer).
  57.  
  58. There are other means to use upper memory in your Turbo Pascal
  59. applications; one of them is the unit UMB_Heap published in PC
  60. Magazine (vol. 11 no. 20).  This unit will map the existing upper
  61. memory blocks in the regular Turbo Pascal heap.  Although this is the
  62. most transparent way to use upper memory, this unit has some
  63. shortcomings:
  64.  
  65.   - a program using this unit could have big problems when trying to
  66.     execute child DOS processes, since Turbo Pascal does not expect its
  67.     memory to be allocated as several DOS memory blocks;
  68.   - the unit itself has some bugs concerning the restoration of the DOS
  69.     memory allocation strategy and tests for the presence of an XMS driver,
  70.     which cannot be installed on a 8086 based computer.
  71.  
  72.  
  73.  
  74. System Requirements
  75. ────────────────────
  76.  
  77.   - TP6 or TP7/BP7
  78.   - A program that uses overlays...
  79.   - Some free UMBs in the system on which your program is to be executed.
  80.     Note that your program will work without UMB, except that no memory
  81.     will be gained.  Since the overhead of the unit is about 320 bytes,
  82.     decrease in available memory will hardly noticeable.
  83.  
  84.  
  85.  
  86. Contents
  87. ─────────
  88.  
  89. The complete package contains:
  90.  
  91.   - ovrumb.doc          This file
  92.  
  93.   - ovrumb.pas          The main unit source
  94.  
  95.   - ovrtest.pas         A test program that demonstrates the use of the
  96.     ovr1.pas            OvrUMB unit.
  97.     ovr2.pas
  98.  
  99.  
  100.  
  101. How to use this unit in your programs
  102. ──────────────────────────────────────
  103.  
  104. This is very easy : the modifications must be done in the main program
  105. or in the initialization part of a unit that is declared before any
  106. overlaid unit.
  107.  
  108.   - Add "OvrUMB" in your uses statement;
  109.   - Instead of code like
  110.  
  111.       ...
  112.       OvrInit('MYPROG.OVR');   {Opens the overlay files}
  113.       OvrSetBuf(MyBufSize);    {Sets the overlay buffer size to MyBufSize,
  114.                 since the default value is often too small}
  115.       ...
  116.  
  117.     use:
  118.  
  119.       ...
  120.       OvrInit('MYPROG.OVR');   {Opens the overlay files}
  121.       OvrSetBuf(MyBufSize);    {Sets the overlay buffer size to MyBufSize,
  122.                 since the default value is often too small}
  123.       OvrMovBufToUMB;          {Tries to move the overlay buffer in upper
  124.                 memory.  It this is not possible,
  125.                 nothing happens}
  126.       ...
  127.  
  128.   - That's all : OvrUMB will automatically free the UMB on exit.
  129.  
  130.  
  131. You can also use the procedure OvrSetBufUMB(Size:longint) that allows
  132. you to specify the size of the wanted buffer.  This function can be
  133. useful if you want to change the buffer size when it is in upper
  134. memory.
  135.  
  136. In order to help you to select the best block size, OvrUMB provides
  137. the function umb_MaxAvail which returns the size of the biggest upper
  138. memory block as a longint.
  139.  
  140. In fact, OvrMovBufToUMB is logically equivalent to:
  141.  
  142.   if umb_MaxAvail>OvrGetBuf then OvrSetBufUMB(umb_MaxAvail);
  143.  
  144. But of course it is more efficient and generate less code.
  145.  
  146. These two procedure will do nothing if they detect any problem and
  147. return an error value in OvrResult.  I have tried to map the error
  148. conditions to existing error codes.
  149.  
  150. The procedures return ovrError when:
  151.   - the overlay file has not be opened (use OvrInit to open it)
  152.   - there are some overlays loaded (use OvrClearBuf to unload them)
  153.   - the heap is not empty
  154.   - the buffer has already been reallocated somewhere
  155.   - you tried to allocate a buffer smaller than the minimum allowed
  156.     (only with OvrSetBufUMB).
  157.  
  158. The procedures return ovrNoMemory when:
  159.   - There is no upper memory manager running
  160.   - There is no big enough upper memory block to contain the overlay
  161.     buffer.
  162.  
  163.  
  164.  
  165. Acknowledgments
  166. ────────────────
  167.  
  168. I would like to thank the testers without whom I could not have
  169. written this unit, since I have no upper memory dispenser on my 286 :-( 
  170. In particular, my thanks go to Mike McWhinney (elja.inc@mixcom.com),
  171. Herbert Zarb (hzarb@unimt.mt) and Jack Nomssi
  172. (Nomssi@Physik.TU-Chemnitz.DE).
  173.  
  174.  
  175.  
  176. Revision history
  177. ─────────────────
  178.  
  179.   version 1.0 (27/10/93)
  180.        First public version.
  181.   version 1.1 (21/07/94)
  182.        Added function umb_MaxAvail;
  183.        OvrMovBufToUMB now tries to allocate the biggest possible block.
  184.   version 1.2 (15/09/94)
  185.        Fixed bug that could make program fail in some cases where there
  186.          are no UMB available.
  187.        Changed the compilation directives of the test program so that 
  188.          they compile on Timo Salmi's PC :-)  
  189.  
  190.  
  191.  
  192. Known Bugs and limitations
  193. ───────────────────────────
  194.  
  195.   - The system will crash if you try to call OvrSetBuf after reallocating
  196.     the overlay buffer in upper memory (however, I don't know why you
  197.     would want to do that...)
  198.   - There might be a compatibility problem with ExecWithSwap (from
  199.     TurboPower Software)
  200.  
  201. If you use this unit (or even if you don't like it), please send me a
  202. message at the address below.  Any feedback that I can get is welcome.
  203.  
  204.  
  205.  
  206. Contacting me
  207. ──────────────
  208.  
  209. Report bugs and send comments and suggestions to:
  210.  
  211.     Jean-Marc Lasgouttes
  212.  
  213.          e-mail  Jean-Marc.Lasgouttes@inria.fr
  214.  
  215.          tel.    (33) 1 39 63 56 40
  216.  
  217.          postal address
  218.                  118, rue Marcadet
  219.                  75018 Paris
  220.                  FRANCE
  221.